<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../../../assets/docs.css" rel="stylesheet" type="text/css" media="screen" />
<title>MooTools 1.3 Documentation - Element/Element.Delegation</title>
</head>

<body>
  <div class="doc">
    <div class="methods">
      <h4 class="menu-item"><a href="#Element">Element</a></h4>
      <div class="menu-item"><a href="#Element:addEvent">addEvent</a></div>
      <div class="menu-item"><a href="#Element:addEvents">addEvents</a></div>
      <div class="menu-item"><a href="#Element:removeEvent">removeEvent</a></div>
      <div class="menu-item"><a href="#Element:removeEvents">removeEvents</a></div>
    </div>
    <div class="l-border r-border span-15 content">
      <h1 id="Element"><a href="#Element">Type: Element</a></h1>
      <p class="description">Extends the <a href="../../../docs/core/Element/Element.html">Element</a> type to include delegations in the addEvent and addEvents methods. It adds the <code>:relay</code> pseudo using <a href="../../../docs/more/Element/Element.Event.Pseudos.html">Element.Event.Pseudos</a>.</p>
      <h3>Notes</h3>
      <ul>
        <li>By delegating events to parent objects you can dramatically increase the efficiency of your pages. Consider the example above. You could attach events to every link on a page - which may be hundreds of DOM elements - or you can delegate the event to the document body, evaluating your code only when the user actually clicks a link (instead of on page load/domready).</li>
        <li>You can use any selector in combination with any event</li>
        <li>You cannot delegate the <em>blur</em> or <em>focus</em> events for elements. This is a limitation in how MooTools manages events internally (and prevents memory leaks) and these two events cannot be delegated until this code is refactored. Look for it in MooTools 2.0.</li>
        <li>Be wary of the cost of delegation; for example, mouseover/mouseout delegation on an entire document can cause your page to run the selector constantly as the user moves his or her mouse around the page. Delegation is not always the best solution.</li>
        <li>Delegation is especially useful if you are using AJAX to load content into your pages dynamically, as the contents of an element can change with new elements added or others removed and your delegated events need not change.</li>
        <li>In general it is always better to delegate to the closest parent to your elements as possible; delegate to an element in the page rather than the document body for example.</li>
      </ul>
      <h3>Credits</h3>
      <p>Event checking based on the work of <a href="http://daniel.steigerwald.cz">Daniel Steigerwald</a>.</p>
      <h2 id="Element:addEvent"><a href="#Element:addEvent">Element method: addEvent</a></h2>
      <p class="description">Delegates the methods of an element's children to the parent element for greater efficiency when a filter is provided. Otherwise works normally as <a href="../../../docs/core/Element/Element.Event.html#Element:addEvent">addEvent</a> always does.</p>
      <h3>Syntax</h3>
      <pre class="javascript">myElement.<span class="me1">addEvent</span><span class="br0">(</span>typeSelector, fn<span class="br0">)</span>;
</pre>
      <h3>Arguments</h3>
      <ol>
        <li>typeSelector - (<em>string</em>) An event name (click, mouseover, etc) that should be monitored paired with a selector (see example) to limit functionality to child elements.</li>
        <li>fn - (<em>function</em>) The callback to execute when the event occurs (passed the event just like any other <a href="../../../docs/core/Element/Element.Event.html#Element:addEvent">addEvent</a> usage and a second argument, the element that matches your selector that was clicked).</li>
      </ol>
      <h3>Example</h3>
      <pre class="javascript"><span class="co1">// Alerts when an anchor element is clicked with class myStyle in myElement</span>
document.<span class="me1">id</span><span class="br0">(</span>myElement<span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'click:relay(a.myStyle)'</span>, <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span>

    <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'hello'</span><span class="br0">)</span>;
<span class="br0">}</span><span class="br0">)</span>;
&nbsp;
&nbsp;
$<span class="br0">(</span>element<span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'click:relay(a)'</span>, <span class="kw2">function</span><span class="br0">(</span>event, clicked<span class="br0">)</span><span class="br0">{</span>

    event.<span class="me1">preventDefault</span><span class="br0">(</span><span class="br0">)</span>; <span class="co1">//don't follow the link</span>
    <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'you clicked a link!'</span><span class="br0">)</span>;
    <span class="co1">//you can reference the element clicked with the second</span>
    <span class="co1">//argument passed to your callback</span>

    clicked.<span class="me1">setStyle</span><span class="br0">(</span><span class="st0">'color'</span>, <span class="st0">'#777'</span><span class="br0">)</span>;
<span class="br0">}</span><span class="br0">)</span>;
</pre>
      <h3>Returns</h3>
      <ul>
        <li> <em>element</em> - This element.</li>
      </ul>
      <h2 id="Element:addEvents"><a href="#Element:addEvents">Element method: addEvents</a></h2>
      <p class="description">Delegates the events to the parent just as with addEvent above. Works as <a href="../../../docs/core/Element/Element.Event.html#Element:addEvents">addEvents</a> does.</p>
      <h3>Example</h3>
      <pre class="javascript">myElement.<span class="me1">addEvents</span><span class="br0">(</span><span class="br0">{</span>
    <span class="co1">//monitor an element for mouseover</span>
    mouseover: fn,
    <span class="co1">//but only monitor child links for click</span>
    <span class="st0">'click:relay(a)'</span>: fn2
<span class="br0">}</span><span class="br0">)</span>;

</pre>
      <h2 id="Element:removeEvent"><a href="#Element:removeEvent">Element method: removeEvent</a></h2>
      <p class="description">Removes a method from an element as <a href="../../../docs/core/Element/Element.Event.html#Element:removeEvent">removeEvent</a> always does.</p>
      <h3>Example</h3>
      <pre class="javascript"><span class="kw2">var</span> monitor = <span class="kw2">function</span><span class="br0">(</span>event, element<span class="br0">)</span><span class="br0">{</span> <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'you clicked a link!'</span><span class="br0">)</span><span class="br0">}</span>;
$<span class="br0">(</span>element<span class="br0">)</span>.<span class="me1">addEvent</span><span class="br0">(</span><span class="st0">'click:relay(a)'</span>, monitor<span class="br0">)</span>;

<span class="co1">//link clicks are delegated to element</span>
&nbsp;
<span class="co1">//...now we remove the delegation:</span>
$<span class="br0">(</span>element<span class="br0">)</span>.<span class="me1">removeEvent</span><span class="br0">(</span><span class="st0">'click:relay(a)'</span>, monitor<span class="br0">)</span>;
</pre>
      <h2 id="Element:removeEvents"><a href="#Element:removeEvents">Element method: removeEvents</a></h2>
      <p class="description">Removes a series of methods from delegation if the functions were used for delegation or else works as <a href="../../../docs/core/Element/Element.Event.html#Element:removeEvents">removeEvents</a> always does.</p>
      <h3>Example</h3>
      <pre class="javascript"><span class="kw2">var</span> monitor = <span class="kw2">function</span><span class="br0">(</span><span class="br0">)</span><span class="br0">{</span>

    <span class="kw3">alert</span><span class="br0">(</span><span class="st0">'you clicked or moused over a link!'</span><span class="br0">)</span>;
<span class="br0">}</span>;
&nbsp;
$<span class="br0">(</span>element<span class="br0">)</span>.<span class="me1">addEvents</span><span class="br0">(</span><span class="br0">{</span>

    <span class="st0">'mouseover:relay(a)'</span>: monitor,
    <span class="st0">'click:relay(a)'</span>: monitor
<span class="br0">}</span><span class="br0">)</span>;
&nbsp;
<span class="co1">// link clicks are delegated to element</span>
<span class="co1">// ...now we remove the delegation:</span>
$<span class="br0">(</span>element<span class="br0">)</span>.<span class="me1">removeEvents</span><span class="br0">(</span><span class="br0">{</span>

    <span class="st0">'mouseover:relay(a)'</span>: monitor,
    <span class="st0">'click:relay(a)'</span>: monitor
<span class="br0">}</span><span class="br0">)</span>;
&nbsp;
<span class="co1">//or we could remove all click:relay(a) events</span>
$<span class="br0">(</span>element<span class="br0">)</span>.<span class="me1">removeEvents</span><span class="br0">(</span><span class="st0">'click:relay(a)'</span><span class="br0">)</span>;

</pre>
    </div>
  </div>
<script type="text/javascript" src="../../../assets/mootools-core-1.3.js"></script>
<script type="text/javascript" src="../../../assets/mootools-more-smoothscroll.js"></script>
<script type="text/javascript" src="../../../assets/doc-assist.js"></script>
</body>
</html>
